Next: Textual Scrolling, Previous: Window Point, Up: Windows [Contents][Index]
Each window maintains a marker used to keep track of a buffer position that specifies where in the buffer display should start. This position is called the display-start position of the window (or just the start). The character after this position is the one that appears at the upper left corner of the window. It is usually, but not inevitably, at the beginning of a text line.
After switching windows or buffers, and in some other cases, if the window start is in the middle of a line, Emacs adjusts the window start to the start of a line. This prevents certain operations from leaving the window start at a meaningless point within a line. This feature may interfere with testing some Lisp code by executing it using the commands of Lisp mode, because they trigger this readjustment. To test such code, put it into a command and bind the command to a key.
This function returns the display-start position of window
window. If window is nil,
the selected window is used.
When you create a window, or display a different buffer in
it, the display-start position is set to a display-start
position recently used for the same buffer, or to
point-min if the buffer doesn’t have
any.
Redisplay updates the window-start position (if you have not specified it explicitly since the previous redisplay)—to make sure point appears on the screen. Nothing except redisplay automatically changes the window-start position; if you move point, do not expect the window-start position to change in response until after the next redisplay.
This function is like window-start, except
that when window is a part of a group of windows
(see Window
Group), window-group-start returns the start
position of the entire group. This condition holds when the
buffer local variable
window-group-start-function is set to a
function. In this case, window-group-start calls
the function with the single argument window, then
returns its result.
This function returns the position where display of its buffer ends in window. The default for window is the selected window.
Simply changing the buffer text or moving point does not
update the value that window-end returns. The
value is updated only when Emacs redisplays and redisplay
completes without being preempted.
If the last redisplay of window was preempted,
and did not finish, Emacs does not know the position of the
end of display in that window. In that case, this function
returns nil.
If update is non-nil,
window-end always returns an up-to-date value
for where display ends, based on the current
window-start value. If a previously saved value
of that position is still valid, window-end
returns that value; otherwise it computes the correct value
by scanning the buffer text.
Even if update is non-nil,
window-end does not attempt to scroll the
display if point has moved off the screen, the way real
redisplay would do. It does not alter the
window-start value. In effect, it reports where
the displayed text will end if scrolling is not required.
This function is like window-end, except that
when window is a part of a group of windows (see
Window Group),
window-group-end returns the end position of the
entire group. This condition holds when the buffer local
variable window-group-end-function is set to a
function. In this case, window-group-end calls
the function with the two arguments window and
update, then returns its result. The argument
update has the same meaning as in
window-end.
This function sets the display-start position of window to position in window’s buffer. It returns position.
The display routines insist that the position of point be
visible when a buffer is displayed. Normally, they change the
display-start position (that is, scroll the window) whenever
necessary to make point visible. However, if you specify the
start position with this function using nil for
noforce, it means you want display to start at
position even if that would put the location of
point off the screen. If this does place point off screen,
the display routines move point to the left margin on the
middle line in the window.
For example, if point is 1 and you set the start of the window to 37, the start of the next line, point will be above the top of the window. The display routines will automatically move point if it is still 1 when redisplay occurs. Here is an example:
;; Here is what ‘foo’ looks like before executing
;; the set-window-start expression.
---------- Buffer: foo ---------- ∗This is the contents of buffer foo. 2 3 4 5 6 ---------- Buffer: foo ----------
(set-window-start (selected-window) (save-excursion (goto-char 1) (forward-line 1) (point))) ⇒ 37
;; Here is what ‘foo’ looks like after executing
;; the set-window-start expression.
---------- Buffer: foo ----------
2
3
∗4
5
6
---------- Buffer: foo ----------
If noforce is non-nil, and
position would place point off screen at the next
redisplay, then redisplay computes a new window-start
position that works well with point, and thus
position is not used.
This function is like set-window-start,
except that when window is a part of a group of
windows (see Window
Group), set-window-group-start sets the
start position of the entire group. This condition holds when
the buffer local variable
set-window-group-start-function is set to a
function. In this case, set-window-group-start
calls the function with the three arguments
window, position, and
noforce, then returns its result. The arguments
position and noforce in this function
have the same meaning as in
set-window-start.
This function returns non-nil if
position is within the range of text currently
visible on the screen in window. It returns
nil if position is scrolled
vertically out of view. Locations that are partially obscured
are not considered visible unless partially is
non-nil. The argument position
defaults to the current position of point in
window; window defaults to the selected
window. If position is t, that means
to check either the first visible position of the last screen
line in window, or the end-of-buffer position,
whichever comes first.
This function considers only vertical scrolling. If
position is out of view only because
window has been scrolled horizontally,
pos-visible-in-window-p returns
non-nil anyway. See Horizontal
Scrolling.
If position is visible,
pos-visible-in-window-p returns t
if partially is nil; if
partially is non-nil, and the
character following position is fully visible, it
returns a list of the form (x
y), where x and y are
the pixel coordinates relative to the top left corner of the
window; otherwise it returns an extended list of the form
(x y rtop
rbot rowh vpos),
where rtop and rbot specify the number
of off-window pixels at the top and bottom of the row at
position, rowh specifies the visible
height of that row, and vpos specifies the
vertical position (zero-based row number) of that row.
Here is an example:
;; If point is off the screen now, recenter it now.
(or (pos-visible-in-window-p
(point) (selected-window))
(recenter 0))
This function is like
pos-visible-in-window-p, except that when
window is a part of a group of windows (see
Window Group),
pos-visible-in-window-group-p tests the
visibility of pos in the entire group, not just in
the single window. This condition holds when the
buffer local variable
pos-visible-in-window-group-p-function is set to
a function. In this case
pos-visible-in-window-group-p calls the function
with the three arguments position,
window, and partially, then returns its
result. The arguments position and
partially have the same meaning as in
pos-visible-in-window-p.
This function returns the height of text line
line in window. If line is
one of header-line or mode-line,
window-line-height returns information about the
corresponding line of the window. Otherwise, line
is a text line number starting from 0. A negative number
counts from the end of the window. The default for
line is the current line in window; the
default for window is the selected window.
If the display is not up to date,
window-line-height returns nil. In
that case, pos-visible-in-window-p may be used
to obtain related information.
If there is no line corresponding to the specified
line, window-line-height returns
nil. Otherwise, it returns a list
(height vpos ypos
offbot), where height is the
height in pixels of the visible part of the line,
vpos and ypos are the vertical position
in lines and pixels of the line relative to the top of the
first text line, and offbot is the number of
off-window pixels at the bottom of the text line. If there
are off-window pixels at the top of the (first) text line,
ypos is negative.
Next: Textual Scrolling, Previous: Window Point, Up: Windows [Contents][Index]